sgdk
bmp.h File Reference

Software bitmap engine. More...

#include "maths.h"
#include "vdp_pal.h"

Go to the source code of this file.

Classes

struct  Bitmap
struct  Pixel
struct  Line
struct  Triangle

Defines

#define BMP_PLAN   APLAN
#define BMP_PLAN_ENUM   PLAN_A
#define BMP_PLANWIDTH_SFT   6
#define BMP_PLANHEIGHT_SFT   6
#define BMP_PLANWIDTH   (1 << BMP_PLANWIDTH_SFT)
#define BMP_PLANHEIGHT   (1 << BMP_PLANHEIGHT_SFT)
#define BMP_CELLWIDTH_SFT   5
#define BMP_CELLWIDTH   (1 << BMP_CELLWIDTH_SFT)
#define BMP_CELLHEIGHT   20
#define BMP_CELLWIDTHMASK   (BMP_CELLWIDTH - 1)
#define BMP_CELLXOFFSET   (((screenWidth >> 3) - BMP_CELLWIDTH) / 2)
#define BMP_CELLYOFFSET   (((screenHeight >> 3) - BMP_CELLHEIGHT) / 2)
#define BMP_XPIXPERTILE_SFT   3
#define BMP_YPIXPERTILE_SFT   3
#define BMP_XPIXPERTILE   (1 << BMP_XPIXPERTILE_SFT)
#define BMP_YPIXPERTILE   (1 << BMP_YPIXPERTILE_SFT)
#define BMP_XPIXPERTILEMASK   (BMP_XPIXPERTILE - 1)
#define BMP_YPIXPERTILEMASK   (BMP_YPIXPERTILE - 1)
#define BMP_WIDTH_SFT   (BMP_CELLWIDTH_SFT + BMP_XPIXPERTILE_SFT)
#define BMP_WIDTH   (1 << BMP_WIDTH_SFT)
#define BMP_HEIGHT   (BMP_CELLHEIGHT * BMP_YPIXPERTILE)
#define BMP_WIDTH_MASK   (BMP_WIDTH - 1)
#define BMP_PITCH_SFT   (BMP_CELLWIDTH_SFT + 2)
#define BMP_PITCH   (1 << BMP_PITCH_SFT)
#define BMP_PITCH_MASK   (BMP_PITCH - 1)
#define BMP_GENBMP16_WIDTH(genbmp16)   ((genbmp16)[0])
#define BMP_GENBMP16_HEIGHT(genbmp16)   ((genbmp16)[1])
#define BMP_GENBMP16_PALETTE(genbmp16)   (&((genbmp16)[2]))
#define BMP_GENBMP16_IMAGE(genbmp16)   (&((genbmp16)[18]))
#define BMP_GETPIXEL(x, y)   bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)]
#define BMP_SETPIXEL(x, y, col)   bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)] = col;
#define BMP_BASETILEINDEX   TILE_USERINDEX
#define BMP_FB0TILEINDEX   BMP_BASETILEINDEX
#define BMP_FB1TILEINDEX   (BMP_BASETILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define BMP_FB0ENDTILEINDEX   (BMP_FB0TILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define BMP_FB1ENDTILEINDEX   (BMP_FB1TILEINDEX + (BMP_CELLWIDTH * BMP_CELLHEIGHT))
#define BMP_BASETILE   (BMP_BASETILEINDEX * 32)
#define BMP_FB0TILE   (BMP_FB0TILEINDEX * 32)
#define BMP_FB1TILE   (BMP_FB1TILEINDEX * 32)
#define BMP_FB0TILEMAP_BASE   BMP_PLAN
#define BMP_FB1TILEMAP_BASE   (BMP_PLAN + ((BMP_PLANWIDTH * (BMP_PLANHEIGHT / 2)) * 2))
#define BMP_FBTILEMAP_OFFSET   (((BMP_PLANWIDTH * BMP_CELLYOFFSET) + BMP_CELLXOFFSET) * 2)

Functions

void BMP_init (u16 double_buffer, u16 palette, u16 priority)
 Initialize the software bitmap engine.
void BMP_end ()
 End the software bitmap engine.
void BMP_reset ()
 Reset the software bitmap engine.
u16 BMP_flip (u16 async)
 Flip bitmap buffer to screen.
void BMP_clear ()
 Clear bitmap buffer.
u8 * BMP_getWritePointer (u16 x, u16 y)
 Get write pointer for specified pixel.
u8 * BMP_getReadPointer (u16 x, u16 y)
 Get read pointer for specified pixel.
u16 BMP_hasFlipRequestPending ()
 Return true (!= 0) if a flip request is pending.
void BMP_waitWhileFlipRequestPending ()
 Wait until no more flip request is pending.
u16 BMP_hasFlipInProgess ()
 Return true (!= 0) if a flip operation is in progress.
void BMP_waitFlipComplete ()
 Wait until the asynchronous flip operation is completed.
Blit operation is the bitmap buffer transfer to VRAM.

void BMP_drawText (const char *str, u16 x, u16 y)
 Draw text in bitmap mode.
void BMP_clearText (u16 x, u16 y, u16 w)
 Clear text in bitmap mode.
void BMP_clearTextLine (u16 y)
 Clear a line of text in bitmap mode.
void BMP_showFPS (u16 float_display)
 Show the frame rate in bitmap mode.
u8 BMP_getPixel (u16 x, u16 y)
 Get pixel at specified position.
void BMP_setPixel (u16 x, u16 y, u8 col)
 Set pixel at specified position.
void BMP_setPixels_V2D (const Vect2D_u16 *crd, u8 col, u16 num)
 Set pixels.
void BMP_setPixels (const Pixel *pixels, u16 num)
 Set pixels.
u8 BMP_clipLine (Line *l)
 Clip the specified line so it fit in bitmap screen (0, 0, BMP_WIDTH, BMP_HEIGHT)
void BMP_drawLine (Line *l)
 Draw a line.
u16 BMP_isPolygonCulled (const Vect2D_s16 *pts, u16 num)
 Determine if the specified polygon is culled.
The polygon points should be defined in clockwise order.
The method returns 1 if the polygon is back faced and should be eliminated for 3D rendering.
u16 BMP_drawPolygon (const Vect2D_s16 *pts, u16 num, u8 col)
 Draw a polygon.
The polygon points should be defined in clockwise order.
Use the BMP_isPolygonCulled(..) method to test if polygon should be draw or not.
void BMP_drawBitmapData (const u8 *data, u16 x, u16 y, u16 w, u16 h, u32 pitch)
 Draw the specified 4BPP bitmap data.
u16 BMP_drawBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 loadpal)
 Draw a Genesis Bitmap.

u16 BMP_drawBitmapScaled (const Bitmap *bitmap, u16 x, u16 y, u16 w, u16 h, u16 loadpal)
 Load and draw a Genesis Bitmap with specified dimension.

void BMP_loadBitmapData (const u8 *data, u16 x, u16 y, u16 w, u16 h, u32 pitch)
void BMP_loadBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 loadpal)
void BMP_loadAndScaleBitmap (const Bitmap *bitmap, u16 x, u16 y, u16 w, u16 h, u16 loadpal)
void BMP_getBitmapPalette (const Bitmap *bitmap, u16 *pal)
void BMP_scale (const u8 *src_buf, u16 src_wb, u16 src_h, u16 src_pitch, u8 *dst_buf, u16 dst_wb, u16 dst_h, u16 dst_pitch)
 Scale the specified source bitmap image to specified dimension.

Variables

u8 * bmp_buffer_read
u8 * bmp_buffer_write

Detailed Description

Software bitmap engine.

Author:
Stephane Dallongeville
Date:
08/2011

This unit provides methods to simulate bitmap mode on SEGA genesis.

The software bitmap engine permit to simulate a 256x160 pixels bitmap screen.
Almost methods as BMP_setPixel and BMP_drawLine however use doubled X pixel so you can consider resolution to be 128x160 in this case.
It uses a double buffer so you can draw to buffer while other buffer is being sent to video memory.
Bitmap buffer requires ~41 KB of memory which is dynamically allocated.
These buffers are transfered to VRAM during blank area, by default on NTSC system the blanking period
is very short so it takes approximately 10 frames to blit an entire buffer.
To improve transfer performance the blank area is extended to fit bitmap resolution:
0-31 = blank
32-191 = active
192-262/312 = blank

With extended blank bitmap can be transfered to VRAM 20 times per second in NTSC
and 25 time per second in PAL.


Define Documentation

#define BMP_CELLHEIGHT   20

Bitmap height (in tile) : 20

#define BMP_CELLWIDTH   (1 << BMP_CELLWIDTH_SFT)

Bitmap width (in tile) : 32

#define BMP_GENBMP16_HEIGHT (   genbmp16)    ((genbmp16)[1])

Get height of genesis bitmap 16 object.

#define BMP_GENBMP16_IMAGE (   genbmp16)    (&((genbmp16)[18]))

Return pointer to image data of genesis bitmap 16 object.

#define BMP_GENBMP16_PALETTE (   genbmp16)    (&((genbmp16)[2]))

Return pointer to palette of genesis bitmap 16 object.

#define BMP_GENBMP16_WIDTH (   genbmp16)    ((genbmp16)[0])

Get width of genesis bitmap 16 object.

#define BMP_GETPIXEL (   x,
 
)    bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)]

Return pixel value at specified location.

Parameters:
xX coordinate.
yY coordinate.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_GETPIXEL(0,0) will actually returns same value as BMP_GETPIXEL((1,0)
Be careful this function does not check for retrieving pixel outside bitmap buffer.

#define BMP_HEIGHT   (BMP_CELLHEIGHT * BMP_YPIXPERTILE)

Bitmap height (in pixel) : 160

#define BMP_PITCH   (1 << BMP_PITCH_SFT)

Bitmap scanline pitch (number of bytes per scanline) : 128

#define BMP_PLAN   APLAN

Plan used to draw bitmap (plan A).

#define BMP_PLANHEIGHT   (1 << BMP_PLANHEIGHT_SFT)

Bitmap plan height (in tile) : 64

#define BMP_PLANWIDTH   (1 << BMP_PLANWIDTH_SFT)

Bitmap plan width (in tile) : 64

#define BMP_SETPIXEL (   x,
  y,
  col 
)    bmp_buffer_write[((y) * BMP_PITCH) + ((x) >> 1)] = col;

Set pixel value at specified position.

Parameters:
xX pixel coordinate.
yY pixel coordinate.
colpixel color.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_SETPIXEL(0,0,..) will actually set same pixel as BMP_SETPIXEL(1,0,..). Be careful this function does not check for retrieving pixel outside bitmap buffer.

#define BMP_WIDTH   (1 << BMP_WIDTH_SFT)

Bitmap width (in pixel) : 256

#define BMP_XPIXPERTILE   (1 << BMP_XPIXPERTILE_SFT)

Number of X pixel per tile : 8 pixels per tile.

#define BMP_YPIXPERTILE   (1 << BMP_YPIXPERTILE_SFT)

Number of y pixel per tile : 8 pixels per tile.


Function Documentation

void BMP_clearText ( u16  x,
u16  y,
u16  w 
)

Clear text in bitmap mode.

Parameters:
xX coordinate (in tile).
yy coordinate (in tile).
wNumber of characters to clear.
void BMP_clearTextLine ( u16  y)

Clear a line of text in bitmap mode.

Parameters:
yy coordinate (in tile).
u8 BMP_clipLine ( Line l)

Clip the specified line so it fit in bitmap screen (0, 0, BMP_WIDTH, BMP_HEIGHT)

Parameters:
lLine to clip.
Returns:
false (0) is the line is entirely outside bitmap screen.
true if at least one pixel is on screen.
u16 BMP_drawBitmap ( const Bitmap bitmap,
u16  x,
u16  y,
u16  loadpal 
)

Draw a Genesis Bitmap.

A Genesis bitmap is automatically created from .bmp or .png file via the rescomp tool.
The resulting file contains bitmap size info and 16 colors palette.

Parameters:
bitmapGenesis Bitmap.
The Bitmap is unpacked "on the fly" if needed (require some memory).
xX coordinate (should be an even value).
yy coordinate.
loadpalLoad the bitmap palette information when non zero.
Returns:
FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

X coordinate is aligned to even value for performance reason.
So BMP_drawBitmap(bitmap,0,0,TRUE) will produce same result as BMP_drawBitmap(bitmap,1,0,TRUE)

void BMP_drawBitmapData ( const u8 *  data,
u16  x,
u16  y,
u16  w,
u16  h,
u32  pitch 
)

Draw the specified 4BPP bitmap data.

Parameters:
data4BPP image data buffer.
xX coordinate (should be an even value for byte alignment).
yy coordinate.
wwidth (should be an even value for byte alignment).
hheight.
pitchbitmap pitch (number of bytes per bitmap scanline).

X coordinate as Width are aligned to even value for performance reason.
So BMP_drawBitmapData(data,0,0,w,h,w) will produce same result as BMP_drawBitmapData(data,1,0,w,h,w)

u16 BMP_drawBitmapScaled ( const Bitmap bitmap,
u16  x,
u16  y,
u16  w,
u16  h,
u16  loadpal 
)

Load and draw a Genesis Bitmap with specified dimension.

A Genesis bitmap is automatically created from .bmp or .png file via the rescomp tool.
The resulting file contains bitmap size info and 16 colors palette.
This method will scale and draw the bitmap with the specified dimension.

Parameters:
bitmapGenesis bitmap.
The Bitmap is unpacked "on the fly" if needed (require some memory).
xX coordinate (should be an even value).
yy coordinate.
wfinal width.
hfinal height.
loadpalLoad the bitmap palette information when non zero.
Returns:
FALSE if there is not enough memory to unpack the specified Bitmap (only if compression was enabled).

X coordinate as width are aligned to even values for performance reason.
So BMP_drawBitmapScaled(bitmap,0,0,w,h,pal) will produce same result as BMP_drawBitmapScaled(bitmap,1,0,w,h,pal)

void BMP_drawLine ( Line l)

Draw a line.

Parameters:
lLine to draw.

Lines are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_drawLine(0,0,0,159) will actually draw same line as BMP_drawLine(1,0,1,159).

u16 BMP_drawPolygon ( const Vect2D_s16 pts,
u16  num,
u8  col 
)

Draw a polygon.
The polygon points should be defined in clockwise order.
Use the BMP_isPolygonCulled(..) method to test if polygon should be draw or not.

Parameters:
ptsPolygon points buffer.
numnumber of point (lenght of points buffer).
colfill color.
Returns:
0 if polygon was not drawn (outside screen or whatever).
void BMP_drawText ( const char *  str,
u16  x,
u16  y 
)

Draw text in bitmap mode.

Parameters:
strString to display.
xX coordinate (in tile).
yy coordinate (in tile).
void BMP_end ( )

End the software bitmap engine.

Release memory used by software bitmap engine (~41 KB).

u16 BMP_flip ( u16  async)

Flip bitmap buffer to screen.

Blit the current bitmap back buffer to the screen then flip buffers so back buffer becomes front buffer and vice versa.
If you use async flag the Bitmap buffer will be sent to video memory asynchronously during blank period and the function return immediatly.
If a flip is already in process then flip request is marked as pending and will be processed as soon the current one complete.
You can use BMP_waitWhileFlipRequestPending() method to ensure no more flip request are pending before writing to bitmap buffer.
If a flip request is already pending the function wait until no more request are pending.

Parameters:
asyncAsynchronous flip operation flag.
Returns:
Only meaningful for async operation:
0 if the flip request has be marked as pending as another flip is already in process.
1 if the flip request has be initiated.
See also:
BMP_hasFlipRequestPending()
BMP_waitWhileFlipRequestPending()
void BMP_getBitmapPalette ( const Bitmap bitmap,
u16 *  pal 
)
Deprecated:
Uses bitmap->palette instead.
u8 BMP_getPixel ( u16  x,
u16  y 
)

Get pixel at specified position.

Parameters:
xX coordinate.
yY coordinate.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_getPixel(0,0) will actually returns same value as BMP_getPixel(1,0).

See also:
BMP_GETPIXEL (faster but not as safe)
u8* BMP_getReadPointer ( u16  x,
u16  y 
)

Get read pointer for specified pixel.

Parameters:
xX pixel coordinate.
yY pixel coordinate.

As coordinates are expressed for 4bpp pixel BMP_getReadPointer(0,0) and BMP_getReadPointer(1,0) actually returns the same address.

u8* BMP_getWritePointer ( u16  x,
u16  y 
)

Get write pointer for specified pixel.

Parameters:
xX pixel coordinate.
yY pixel coordinate.

As coordinates are expressed for 4bpp pixel BMP_getWritePointer(0,0) and BMP_getWritePointer(1,0) actually returns the same address.

void BMP_init ( u16  double_buffer,
u16  palette,
u16  priority 
)

Initialize the software bitmap engine.

Parameters:
double_bufferEnabled VRAM double buffer.
VRAM Double buffer permit to avoid image tearing because of partial screen refresh.
It requires almost all VRAM tiles space (~41 KB) so enable it only if you don't need other plan or sprites.
palettePalette index to use to render the bitmap plan.
Set it to 0 if unsure.
prioritySet the priority of bitmap plan.
0 = low priority (default).
1 = high priority.

Requires ~41 KB of memory which is dynamically allocated.

u16 BMP_isPolygonCulled ( const Vect2D_s16 pts,
u16  num 
)

Determine if the specified polygon is culled.
The polygon points should be defined in clockwise order.
The method returns 1 if the polygon is back faced and should be eliminated for 3D rendering.

Parameters:
ptsPolygon points buffer.
numnumber of point (lenght of points buffer).
Returns:
1 if polygon is culled (should not be draw) and 0 otherwise.
void BMP_loadAndScaleBitmap ( const Bitmap bitmap,
u16  x,
u16  y,
u16  w,
u16  h,
u16  loadpal 
)
Deprecated:
Use BMP_drawBitmapEx(..) instead.
void BMP_loadBitmap ( const Bitmap bitmap,
u16  x,
u16  y,
u16  loadpal 
)
Deprecated:
Use BMP_drawBitmap(..) instead.
void BMP_loadBitmapData ( const u8 *  data,
u16  x,
u16  y,
u16  w,
u16  h,
u32  pitch 
)
Deprecated:
Use BMP_drawBitmapData(..) instead.
void BMP_reset ( )

Reset the software bitmap engine.

Rebuild tilemap for bitmap engine and clear buffers.

void BMP_scale ( const u8 *  src_buf,
u16  src_wb,
u16  src_h,
u16  src_pitch,
u8 *  dst_buf,
u16  dst_wb,
u16  dst_h,
u16  dst_pitch 
)

Scale the specified source bitmap image to specified dimension.

Take a source bitmap with its specified dimension and scale it in the
destination buffer with specified dimension.

Parameters:
src_bufsource bitmap buffer.
src_wbsource width in byte.
src_hsource height.
src_pitchsource pitch (number of bytes per scanline).
dst_bufdestination bitmap buffer.
dst_wbdestination width in byte.
dst_hdestination height.
dst_pitchdestination pitch (number of bytes per scanline).
void BMP_setPixel ( u16  x,
u16  y,
u8  col 
)

Set pixel at specified position.

Parameters:
xX pixel coordinate.
yY pixel coordinate.
colpixel color.

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_setPixel(0,0,..) will actually set same pixel as BMP_setPixel(1,0,..).

See also:
BMP_SETPIXEL (faster but not as safe)
void BMP_setPixels ( const Pixel pixels,
u16  num 
)

Set pixels.

Parameters:
pixelsPixels buffer.
numnumber of pixel to draw (lenght of pixels buffer).

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_setPixel(0,0,..) will actually set same pixel as BMP_setPixel(1,0,..).

void BMP_setPixels_V2D ( const Vect2D_u16 crd,
u8  col,
u16  num 
)

Set pixels.

Parameters:
crdCoordinates buffer.
colpixels color.
numnumber of pixel to draw (lenght of coordinates buffer).

Pixels are rendereded with X doubled resolution (byte operation) for performance reason.
So BMP_setPixel(0,0,..) will actually set same pixel as BMP_setPixel(1,0,..).

void BMP_showFPS ( u16  float_display)

Show the frame rate in bitmap mode.

Parameters:
float_displayIf this value is true (!= 0) the frame rate is displayed as float (else it's integer).

Variable Documentation

Current bitmap read buffer.

Current bitmap write buffer.

 All Classes Files Functions Variables Typedefs Enumerations Defines